# 快速上手

## 在线示例

我们提供了基于 Rsbuild 的在线示例，通过示例项目，你可以直观感受 Rspack 的构建性能和 Rsbuild 的开发体验：

- [Rsbuild CodeSandbox 示例](https://codesandbox.io/p/github/rspack-contrib/rsbuild-codesandbox-example)

你也可以使用 [豆包 MarsCode](https://www.marscode.cn/) 快速创建一个在线的 Rsbuild 项目：

1. 访问 [MarsCode - Rsbuild 模板](https://www.marscode.cn/dashboard/template-detail?id=8e8qr0k282d6wn)。
2. 登录，点击右上角的「使用模板」按钮即可。

## 环境准备

Rsbuild 支持使用 [Node.js](https://nodejs.org/)、[Deno](https://deno.com/) 或 [Bun](https://bun.sh/) 作为运行时。

### Node.js

对于 Node.js，请安装 Node.js >= 16 版本，推荐使用 Node.js LTS 版本。

通过以下命令检查当前使用的 Node.js 版本：

```bash
node -v
```

如果你的环境中尚未安装 Node.js，或是版本过低，可以通过 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 安装。

下面是通过 nvm 安装的例子：

```bash
# 安装 Node.js LTS
nvm install --lts
# 切换到 Node.js LTS
nvm use --lts
```

## 创建 Rsbuild 项目

你可以使用 `create-rsbuild` 来创建一个 Rsbuild 项目，调用以下命令：

import { PackageManagerTabs } from '@theme';

<PackageManagerTabs
  command={{
    npm: 'npm create rsbuild@latest',
    yarn: 'yarn create rsbuild',
    pnpm: 'pnpm create rsbuild@latest',
    bun: 'bun create rsbuild@latest',
  }}
/>

然后按照提示操作即可。

### 模板

在创建项目时，你可以选择 `create-rsbuild` 提供的下列模板：

| 模板    | 描述                            | 可选功能   |
| ------- | ------------------------------- | ---------- |
| vanilla | 原生 JavaScript                 | TypeScript |
| react   | [React 19](https://react.dev/)  | TypeScript |
| vue3    | [Vue 3](https://vuejs.org/)     | TypeScript |
| vue2    | [Vue 2](https://v2.vuejs.org/)  | TypeScript |
| lit     | [Lit](https://lit.dev/)         | TypeScript |
| preact  | [Preact](https://preactjs.com/) | TypeScript |
| svelte  | [Svelte 5](https://svelte.dev/) | TypeScript |
| solid   | [Solid](https://solidjs.com/)   | TypeScript |

### 可选工具

`create-rsbuild` 能够帮助你设置一些常用的工具，包括 [Biome](https://github.com/biomejs/biome)、[ESLint](https://github.com/eslint/eslint) 和 [prettier](https://github.com/prettier/prettier)，你可以使用上下箭头和空格进行选择。如果你不需要这些工具，可以直接按回车跳过。

```text
◆  Select additional tools (Use <space> to select, <enter> to continue)
│  ◻ Add Biome for code linting and formatting
│  ◻ Add ESLint for code linting
│  ◻ Add Prettier for code formatting
└
```

:::tip
Biome 提供与 ESLint 和 Prettier 相似的代码检查和格式化功能。如果你选择了 Biome，通常就不需要再选择 ESLint 或 Prettier 了。
:::

### 当前目录

如果你需要在当前目录下创建项目，可以将 target folder 设置为 `.`：

```text
◆  Create Rsbuild Project
│
◇  Project name or path
│  .
│
◇  "." is not empty, please choose:
│  Continue and override files
```

### 快速创建

[create-rsbuild](https://www.npmjs.com/package/create-rsbuild) 提供了一些 CLI 选项。通过设置这些 CLI 选项，你可以跳过交互式的选择步骤，一键创建项目。

比如，一键创建 React 项目到 `my-project` 目录：

```bash
npx create-rsbuild --dir my-project --template react

# 使用缩写
npx create-rsbuild -d my-project -t react
```

`create-rsbuild` 完整的 CLI 选项如下：

```text
Usage: create-rsbuild [options]

Options:

  -h, --help       display help for command
  -d, --dir        create project in specified directory
  -t, --template   specify the template to use
  --tools          select additional tools (biome, eslint, prettier)
  --override       override files in target directory

Templates:

  react-js, react-ts, vue3-js, vue3-ts, vue2-js, vue2-ts, svelte-js, svelte-ts, solid-js, solid-ts, vanilla-js, vanilla-ts
```

## 从现有项目迁移

如果你需要从一个现有项目迁移迁移到 Rsbuild，可以参考以下指南：

- [从 webpack 迁移](/guide/migration/webpack)
- [从 Create React App 迁移](/guide/migration/cra)
- [从 Vue CLI 迁移](/guide/migration/vue-cli)
- [从 Vite 迁移](/guide/migration/vite)
- [从 Modern.js Builder 迁移](/guide/migration/modern-builder)

### 其他项目

对于其他类型的项目，你可以手动安装 [@rsbuild/core](https://www.npmjs.com/package/@rsbuild/core) 包：

<PackageManagerTabs command="add @rsbuild/core -D" />

然后参考指南和文档，按需启用各个功能：

- 参考 [CLI 工具](/guide/basic/cli) 来了解可用的 CLI 命令。
- 参考 [插件列表](/plugins/list/index) 来选择 Rsbuild 插件。
- 参考 [配置 Rsbuild](/guide/basic/configure-rsbuild) 进行配置。

## 命令行工具

Rsbuild 内置了一个轻量的命令行工具，包含 dev、build 等命令。

```json title="package.json"
{
  "scripts": {
    // 启动开发服务器
    "dev": "rsbuild dev",
    // 构建用于生产的应用
    "build": "rsbuild build",
    // 在本地预览生产版本
    "preview": "rsbuild preview"
  }
}
```

请参考 [CLI 工具](/guide/basic/cli) 来了解所有可用的命令以及选项。

## 入口模块

Rsbuild CLI 默认会使用 `src/index.(js|ts|jsx|tsx)` 作为入口模块，你可以使用 [source.entry](/config/source/entry) 配置项来修改入口模块。

## 核心 npm 包

### @rsbuild/core

<a
  href="https://npmjs.com/package/@rsbuild/core"
  target="_blank"
  style={{ display: 'block', marginTop: '16px' }}
>
  <img
    src="https://img.shields.io/npm/v/@rsbuild/core?style=flat-square&colorA=564341&colorB=EDED91"
    alt="@rsbuild/core"
    style={{ pointerEvents: 'none' }}
  />
</a>

Rsbuild 核心包，提供 CLI 命令和 JavaScript API。

### create-rsbuild

<a
  href="https://npmjs.com/package/create-rsbuild"
  target="_blank"
  style={{ display: 'block', marginTop: '16px' }}
>
  <img
    src="https://img.shields.io/npm/v/create-rsbuild?style=flat-square&colorA=564341&colorB=EDED91"
    alt="create-rsbuild"
    style={{ pointerEvents: 'none' }}
  />
</a>

用于创建 Rsbuild 新项目。

## 下一步

你可能想要：

import NextSteps from '@components/NextSteps';
import Step from '@components/Step';

<NextSteps>
  <Step
    href="/guide/start/features"
    title="功能导航"
    description="了解 Rsbuild 提供的所有功能"
  />
  <Step
    href="/guide/basic/configure-rsbuild"
    title="查阅配置"
    description="了解如何配置 Rsbuild"
  />
  <Step
    href="/guide/start/glossary"
    title="名词解释"
    description="了解 Rsbuild 相关的概念"
  />
</NextSteps>
